home *** CD-ROM | disk | FTP | other *** search
/ Atari Mega Archive 1 / Atari Mega Archive - Volume 1.iso / mint / mint96sb.zoo / doc / filesys.doc < prev    next >
Text File  |  1992-09-09  |  35KB  |  723 lines
  1. MiNT File Systems
  2.  
  3. MiNT allows loadable file systems, which means that it should be quite
  4. easy to implement networked file systems, dynamically re-sizable ram
  5. disks, or other nifty things (for example, Stephen Henson's minix.xfs
  6. file system allows access to Minix partitions from TOS). Writing
  7. these is not difficult, but there are a lot of data structures that
  8. must be understood first. (These data structures are given in the
  9. file "filesys.h".)
  10.  
  11. A note on conventions: a declaration like:
  12.     short foo P_((char *bar, long baz));
  13. means that "foo" is a function that returns a 16 bit integer, and that
  14. expects a pointer to a character and a 32 bit integer as its two
  15. arguments. "ushort" is an unsigned 16 bit integer; "ulong" is an
  16. unsigned 32 bit integer.
  17.  
  18. File Cookies
  19.  
  20. Files and directories are represented in the kernel by "cookies".
  21. The contents of the cookie are mostly file system dependent, i.e. the
  22. kernel interprets only the "fs" and "dev" field of the cookie, and the
  23. contents of the other fields may be used by a file system as it sees fit.
  24.  
  25. A file cookie has the following structure:
  26.  
  27. typedef struct f_cookie {
  28.     FILESYS *fs;        /* file system that knows about this cookie */
  29.     ushort    dev;        /* device info (e.g. Rwabs device number) */
  30.     ushort    aux;        /* extra data that the file system may want */
  31.     long    index;        /* this+dev uniquely identifies a file */
  32. } fcookie;
  33.  
  34. (The "FILESYS" data type is defined below.)
  35. The interpretation of the "aux" field is entirely file system dependent. The
  36. "index" field is not presently used by the kernel, but file systems
  37. should (if possible) make this field uniquely identify a file or directory
  38. on a device.
  39.  
  40. File System Structure
  41.  
  42. This is the structure that tells the kernel about the file system,
  43. and gives the entry points for routines which the kernel can call in order
  44. to manipulate files and directories. Note that actual input/output
  45. operations are performed by a device driver; most file systems have just
  46. one associated device driver, but some may have more. See the section on
  47. device drivers for more information on these.
  48.  
  49. Unless otherwise specified, all of the functions should return 0 for
  50. success and an appropriate (long negative) error code for failure. Also,
  51. note that it is the kernel's responsibility to do all access checking;
  52. the file system may assume that the file's permissions have been checked
  53. and are compatible with the current process' uid and the operation
  54. selected.
  55.  
  56. Parameters are passed to file system driver functions on the stack.
  57. The file system drivers should preserve registers d2-d7 and a2-a7,
  58. and return any results in register d0. Note that this may differ from
  59. your compiler's default conventions (for example, Alcyon C preserves
  60. only registers d3-d7 and a3-a7); in this case, an assembly language
  61. wrapper will be necessary.
  62.  
  63. typedef struct filesys {
  64.     struct    filesys    *next;
  65.  
  66. This is a link to the next file system in the kernel's list. It will be
  67. filled in by the kernel; the file system should leave it as NULL.
  68.  
  69.     long    fsflags;
  70. These flags give some information about the file system. Currently, three
  71. flags are defined:
  72.  
  73. #define FS_KNOPARSE     0x01    /* kernel shouldn't do parsing */
  74. #define FS_CASESENSITIVE 0x02    /* file names are case sensitive */
  75. #define FS_NOXBIT     0x04    /* if a file can be read, it can be executed */
  76.  
  77. Other bits may be defined in future releases of MiNT; for now all other
  78. bits in this flag should be 0. Most file systems will have only the
  79. FS_NOXBIT flag; networked file systems may have FS_KNOPARSE for
  80. reasons of efficiency, and file systems that must be compatible with Unix
  81. or similar specifications may be case sensitive and hence have FS_CASESENSITIVE
  82. set.
  83.  
  84.     long    (*root) P_((short drv, fcookie *fc));
  85. This is the entry point for a routine to find a file cookie for the root
  86. directory of BIOS device "drv" (an integer in the range 0-31 inclusive).
  87. This function is called by the kernel when initializing a drive; the kernel
  88. will query each file system in turn for a file cookie representing the
  89. root directory of the drive. If the file system recognizes the data on
  90. the drive as being valid for a file system that it recognizes, it should
  91. fill in the cookie pointed to by "fc" and return 0. Otherwise, it should
  92. return a negative error code (EDRIVE is a good choice) to indicate that the
  93. drive must belong to another file system. Note that this function is called
  94. at boot up time and also at any time when media change is detected on a drive.
  95.  
  96.     long    (*lookup) P_((fcookie *dir, char *name, fcookie *fc));
  97. Translate a file name into a cookie. "dir" is the cookie for a directory,
  98. returned by a previous call to (*lookup) or (*root). "name" is either the
  99. name of a file in that directory (if fsflags & FS_KNOPARSE == 0) or a path
  100. name relative to that directory (if fsflags & FS_KNOPARSE == FS_KNOPARSE).
  101. If the file is not found, an appropriate error code (like EFILNF) should be
  102. returned. If the file is found, the cookie "*fc" should be filled in with
  103. appropriate data, and either 0 or EMOUNT returned. EMOUNT should be returned
  104. only if "name" is ".." and "dir" represents the root directory of a drive;
  105. 0 should be returned otherwise. Note that a lookup call with a null name
  106. or with "." should always succeed and return a cookie representing the
  107. directory itself. Also note that symbolic links should *never* be followed.
  108.  
  109.     long    (*creat) P_((fcookie *dir, char *name, ushort mode,
  110.                 short attrib, fcookie *fc)
  111. Create a new file named "name" in the directory whose cookie is "dir".
  112. "mode" gives the file's type and access permissions, as follows:
  113.     /* file types */
  114.     #define S_IFMT    0170000        /* mask to select file type */
  115.     #define S_IFCHR    0020000        /* BIOS special file */
  116.     #define S_IFDIR    0040000        /* directory file */
  117.     #define S_IFREG 0100000        /* regular file */
  118.     #define S_IFIFO 0120000        /* FIFO */
  119.     #define S_IMEM    0140000        /* memory region or process */
  120.     #define S_IFLNK    0160000        /* symbolic link */
  121.  
  122.     /* special bits: setuid, setgid, sticky bit */
  123.     #define S_ISUID    04000        /* change euid when executing this file */
  124.     #define S_ISGID 02000        /* change egid when executing this file */
  125.     #define S_ISVTX    01000        /* not implemented */
  126.  
  127.     /* file access modes for user, group, and other*/
  128.     #define S_IRUSR    0400        /* read access for user */
  129.     #define S_IWUSR 0200        /* write access for user */
  130.     #define S_IXUSR 0100        /* execute access for user */
  131.     #define S_IRGRP 0040        /* ditto for group... */
  132.     #define S_IWGRP    0020
  133.     #define S_IXGRP    0010
  134.     #define S_IROTH    0004        /* ditto for everyone else */
  135.     #define S_IWOTH    0002
  136.     #define S_IXOTH    0001
  137.  
  138. "attrib" gives the standard TOS attribute byte. This is slightly redundant
  139. with "mode" (i.e. the FA_RDONLY bit should agree with the settings of
  140. S_IWUSR, S_IWGRP, and S_IWOTH, and FA_DIR should be set if and only if
  141. the file's format is S_IFDIR) but is provided for convenience for standard
  142. DOS compatible file systems.
  143.  
  144. The kernel will make the "creat" call only after using "lookup" in an attempt
  145. to find the file. The file system should create the file (if possible) and
  146. set the cookie pointed to by "fc" to represent the newly created file.
  147. If an error of any sort occurs, an appropriate error number is returned,
  148. otherwise 0 is returned. Also note that the kernel will not try to
  149. create directories this way; it will use "mkdir" (q.v.) instead.
  150.  
  151.     DEVDRV *(*getdev) P_((fcookie *fc, long *devspecial))
  152. Get the device driver which should be used to do i/o on the file whose
  153. cookie is "fc". If an error occurs, a NULL pointer should be returned
  154. and an error code placed in the long pointed to by "devspecial"; otherwise,
  155. "devspecial" should be set to a device-driver specific value which will
  156. be placed by the kernel in the "devinfo" field of the FILEPTR structure
  157. passed to the device driver's open routine. (The interpretation of
  158. this value is a matter for the file system and the device driver, the
  159. kernel doesn't care.)
  160.  
  161. If the call to (*getdev) succeeds, a pointer to a device driver structure
  162. (see below) is returned; if it fails, a NULL pointer should be returned and
  163. an appropri